home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Tool Chest / Testing & Debugging / Mac OS Development Toolkit / Automation Essentials 2.3.0 / Host Automation Folder / LaunchQuit Engine / LaunchQuit Script.vu < prev    next >
Encoding:
Text File  |  1998-03-19  |  62.1 KB  |  1,326 lines  |  [TEXT/MPS ]
  1. #/******************* This is a full line in MPW printing on an 8.5 x 11, in Courier 9 ******************/
  2. #########################################################################
  3. #########################################################################
  4. ##                     Copyright © Apple Computer, Inc. 1992-1997
  5. ##                                All rights reserved
  6. #########################################################################
  7. #########################################################################
  8. #    
  9. #    Library:        LaunchQuit Script.vu
  10. #    
  11. #    Version:        2.1.4
  12. #    Description:    
  13. #        This script is a shell for the LaunchQuit Engine, a Virtual User task 
  14. #        named CheckLaunchQuits() that executes launchquit test defs. The launchquit
  15. #        engine is in another library named 'LaunchQuits.lib. The parameters
  16. #        are used to determine which tests to run and how many times to repeat each 
  17. #        one, variations in their order or manner of execution, how much detail to 
  18. #        report in the VU Notebook, how to set up the target, and other details of a 
  19. #        fully automated runtime environment.
  20. #    
  21. #        The main goals are: 
  22. #        •    Be the front end for the engine; this script has a crude user interface, 
  23. #            basically the VU script parameter window with creative parameter names and
  24. #            default values.
  25. #        •    Provide a rich set of runtime controls and at the same time keep the 
  26. #            engine simple according to the Clouseau test def based model; this 
  27. #            script is distinct from the engine and calls it as a subroutine.
  28. #        •    Allow execution of any test def(s) directly, without having to wait 
  29. #            for them to occur in their natural order in a stored list; a separate
  30. #            library contains the test defs and tasks required to look up a specific
  31. #            test def based on a wide range of criteria. See the libraries named 
  32. #            PreCompile LQs.vu and LaunchQuit Test Defs.vulib, for full details. Of course, 
  33. #            the engine must support these new retrieval methods, but it does this by 
  34. #            using a task reference variable and standardizing the new methods. 
  35. #        •    Allow blocking the execution execution of any test def(s) for any reason;
  36. #            the LaunchQuit engine has a parameter to specify the list of test defs 
  37. #            to be skipped, by partial or full name.
  38. #        •    Provide access to the TargetControl configuration tasks, so any subset
  39. #            of launchquits can execute multiple times under different settings without 
  40. #            human intervention required; a separate set of libraries in the Clouseau
  41. #            folder contains tasks to set the most commonly used control panels.
  42. #        •    Communicate with the user before the testing begins if the target can not 
  43. #            be prepared; the script attempts to notify as soon as possible if testing
  44. #            is blocked, to require only a small amount of startup babysitting.
  45. #        •    Facilitate easy reproducibility; this happens naturally because of the 
  46. #            features listed above, but the script also allows specification of the
  47. #            random seed for reproducing the pseudo-random choices.
  48. #    Contains:
  49. #        script        LaunchQuit()
  50. #        PrintLQInstructions()
  51. #    
  52. #    History:
  53. #        Date:        By:                Changes:
  54. #        12/20/92    SBR                Created
  55. #        03/22/94    SBR                Added Print_Instructions; changed Repeat_? script 
  56. #                                    parameters to Iterate_?; added Use_MacsBug_Log_Macro 
  57. #                                    parameter; cleaned up formatting.
  58. #        06/17/94    Gary Kratzer    Added PPC launch parameter
  59. #        09/07/94    SBR                Added checkExternalToolVersions();
  60. #                                    added script parameters: report_to_phoenix, 
  61. #                                    printer_selection
  62. #        07/19/95    SBR                Moved checkExternalToolVersions() and 
  63. #                                        TurnOffShutdownWarning() to target_control.lib;
  64. #                                        removed Custom_Testing 
  65. #        08/03/95    SBR        Radar 1274932:    print all parameters for ISO compliance
  66. #                            Radar 1274933:    better defaults if Use_Development_TDs := true
  67. #                            Radar 1274934:    added "PDD Maker GX" printer selection
  68. #                            Radar 1274935:    removed Custom_Testing parameter
  69. #                            Radar 1274936:    removed Use_Arbitrator_If_Available parameter
  70. #        09/27/96    BRL        Added SPEC Exception handling
  71. #        01/10/97    SBR        Updated PrintLQInstructions() for LQ Engine 2.1d6
  72. #        01/30/97    SBR        Deleted older exception code and comments.
  73. #        01/31/97    SBR        Changed AIQ LaunchQuits.vuLib to LaunchQuit Test Defs.vuLib.
  74. #        01/31/97    SBR        Retired VUAidFKEY.
  75. #        04/10/97    SBR        Changed name to LaunchQuit Script.vu (for TTS compatibility).
  76. #########################################################################
  77. #########################################################################
  78. Libraries
  79.     # Clouseau libraries
  80.     "Additions.lib", 
  81.     "Clouseau.lib", 
  82.     "MemoryCP.lib", 
  83.     "Message.lib", 
  84.     "Report.lib",
  85.     "TargetControl.lib",
  86.     "VUAid.lib", 
  87.     
  88.     # LaunchQuit libraries
  89.     "Dev LaunchQuits",
  90.     "LaunchQuit Test Defs.vuLib", 
  91.     "LaunchQuits.lib",
  92.  
  93.     # External Tool libraries
  94.     "FileTool.vuLib",
  95.     #"OnTarget.lib"
  96.     
  97.     # SPEC libraries
  98.     "ExceptionHandling.lib",
  99.     "Globals.lib";
  100.  
  101. #########################################################################
  102. #    script            LaunchQuit()
  103. #∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
  104. #    Description:    Provides a front end for the LaunchQuit Engine as described in the
  105. #                    header for this library file.
  106. #    Parameters:        The parameters are so numerous they are divided into several sections
  107. #                    for readability. Each section contains parameters that roughly partain
  108. #                    to the same kind of setting, such as: which test defs to execute, 
  109. #                    how to configure the target, and various switches to modify the 
  110. #                    behavior of the engine.
  111. #    
  112. #        Print_Instructions
  113. #            Possible values are:
  114. #                true:    Print the instructions for how to use the script parameters, 
  115. #                        then exit the script.
  116. #                false:    Execute the script normally. Do not print instructions.
  117. #    
  118. #        Run_Title
  119. #            This is just a string the engine puts into the notebook as an 
  120. #            identifier for someone reading the log later. It can be anything 
  121. #            you want. For example, you might use 
  122. #            'Quadra 840AV GMc4 Acceptance Launchquits with EtherNet'.
  123. #    
  124. #        Report_To_Phoenix
  125. #            This is a Boolean to switch on and off TCS reporting to Phoenix from 
  126. #            the LaunchQuit Engine. For a description of TCS reporting, refer to 
  127. #            the HitchHiker's Guide to SPEC S&L.
  128. #                true:     report test def results to a Phoenix database
  129. #                        through the Results Express external tool
  130. #                false:     do not report test def results externally
  131. #                
  132. #    TEST DEF SELECTION
  133. #    This section allows you to specify which test defs you want to execute and how to 
  134. #    execute them. It partains to the method of launching, a switch for randomness, and how
  135. #    to resume from stopping in the middle of the script.
  136. #    
  137. #        Test_Type
  138. #            The type of test you want to run, similar to the tier for 
  139. #            application compatibility testing. Test defs can be divided into 
  140. #            types 1, 2, and 3, with type 1 being the kind you want to run every 
  141. #            time, and 3 the kind you want to run least often. Currently, all 
  142. #            Launchquits are type 1.
  143. #    
  144. #        Skip_These_Tests
  145. #            A list of test defs never to use under any circumstances. Include 
  146. #            the string or regular expression name(s) of the application(s) you 
  147. #            want to skip for this run of the engine. They will be logged as 
  148. #            Incomplete tests in the Notebook. The name can be partial, but only 
  149. #            the first occurrance counts. The items are removed from the list as 
  150. #            they are skipped. If the name does not end in '@' then it is assumed 
  151. #            to be a partial name and a trailing '≈' is added. For example: 
  152. #            { /≈PageMaker≈/, 'Adobe Premiere' } will skip these two and run all 
  153. #            others. This parameter overides all others.
  154. #    
  155. #        Run_Only_These_Tests
  156. #            A list of test defs to test, if you want to use a subset. Include 
  157. #            the string or regular expression name(s) of the application(s) you 
  158. #            want to test during this run of the engine. If there are any items in 
  159. #            this list the engine will use ONLY the listed test defs. The other 
  160. #            applications are ignored and not logged. This is most useful for 
  161. #            iterating a specific test def for regression. The name can be 
  162. #            partial, but only the first occurrance counts. The items are 
  163. #            removed from the list as they are used. If the name does not end in 
  164. #            '@' then it is assumed to be a partial name and a trailing '≈' is 
  165. #            added. For example: { /≈PageMaker≈/, 'Adobe Premiere' } will run 
  166. #            ONLY these two.
  167. #    
  168. #            NOTE: If the same name is in Skip_These_Tests and Run_Only_These_Tests, 
  169. #            then the request to skip takes priority over the request to run.
  170. #    
  171. #        Iterate_Each_Test
  172. #            An integer specifying how many times to iterate each test def 
  173. #            which is not skipped. This parameter is useful for stress testing.
  174. #    
  175. #        Random_Order_Once_Each
  176. #            Changes the order of execution. The engine will execute all test 
  177. #            defs in pseudo-random order, but none will execute more than once, 
  178. #            unless Iterate_Each_Test is greater than one. Possible values are:
  179. #                true:    Test defs execute in pseudo-random order.
  180. #                false:    Test defs execute in natural order, which is alphabetic.
  181. #    
  182. #        Random_Seed
  183. #            Used when trying to reproduce pseudo-random tests. Before using VU's
  184. #            random number generator, the script prints the random seed in the 
  185. #            Notebook. If you want to reproduce a test run then copy the seed from 
  186. #            the Notebook and paste it in this parameter. Possible values are:
  187. #                zero:        Allow VU create a new random seed.
  188. #                integer:    Set the random seed to the specified value.
  189. #    
  190. #        Launch_Method
  191. #            This allows you to specify how you want to launch the application. 
  192. #            The most reliable method is 'Finder'. The fastest is 'auto'.
  193. #            The possible values are:
  194. #                'AgentVUFG':    Launch by creator into the foreground using Agent VU.
  195. #                'AgentVUBG':    Launch by creator into the background using Agent VU. 
  196. #                                Since most applications do not launch properly into 
  197. #                                the background, this method is not allowed unless 
  198. #                                launchParams contains 'bgLaunchOK'.
  199. #                    CAUTION:    Agent VU 2.0.x will not launch an app if the 
  200. #                                preferred size is not available. Since Agent VU uses 
  201. #                                the creator, that should be unique across all 
  202. #                                mounted target volumes.
  203. #                'Find File':    Locate using FInd File DA. Double-click while 
  204. #                                pressing the option key to close the DA.
  205. #                                This method is slow but sure if the names are unique.
  206. #                'Finder':        Twitch to Finder and Find appName. Type command-O 
  207. #                                while pressing the option key to close the window.
  208. #                                This method is not reliable with newer Finders.
  209. #                'auto':            Use 'agentVUFG', but if this is fails use 'Finder'.
  210. #    
  211. #        Special_Parameters
  212. #            Launch only the applications with the specified launch parameters. 
  213. #            This is mainly used to test under known failure conditions. 
  214. #            Possible values are:
  215. #                'FPU':            The application expects the target to have an FPU.
  216. #                '32Bit':        The application crashes under 32-bit addressing.
  217. #                '68040 Caches':    The application crashes if 68040 Caches are on.
  218. #                'QuickTime':    The application expects the target to have QuickTime.
  219. #                'noCreatorLaunch':    There are multiple applications across the 
  220. #                                target volumes which have this creator. 
  221. #                'bgLaunchOK':    The application can launch into the background.
  222. #                'SNConflict':    The application uses network-based serial number 
  223. #                                copy protection.                 
  224. #                'PPC':            The application only runs on a PowerPC.
  225. #    
  226. #        Resume_Last_Run
  227. #            If for some reason you stop the Launchquit script prematurely, 
  228. #            you can resume at any application by putting its name in this 
  229. #            parameter. You can use a partial or exact name. The best way is to 
  230. #            copy the exact name of the last attempted test def from the 
  231. #            Notebook. If you were using the Arbitrator when you stopped, and 
  232. #            it is still running when you start, it will automatically provide 
  233. #            the last attempted test def as the resume value.
  234. #    
  235. #        Resume_Offset
  236. #            Using this if you want to resume at some test def after the one
  237. #            specified in Resume_Last_Run. Include an integer representing the
  238. #            offset from the original. The engine will find the nth test def that
  239. #            matches Special_Parameters. For example, the last test def executed
  240. #            before you stopped the engine might be 'SimAnt'. Usually, if SimAnt 
  241. #            failed, you will want to resume at the next one, so put 'SimAnt' 
  242. #            in Resume_Last_Run and 1 into the Resume_Offset. If you want to 
  243. #            resume with 'SimAnt', use a zero here. You can not use negative 
  244. #            offsets, but the number may be as high as the number of test defs
  245. #            matching Special_Parameters.
  246. #    
  247. #    TARGET SETUP
  248. #    This section allows you to specify how to set up the Memory Control Panel, and how many times 
  249. #    you want to run through all the test defs in each configuration. To use this feature, the 
  250. #    VUAid 2.0 External Tool must be on the Target.
  251. #    
  252. #        Configurations__0_Is_Custom
  253. #            For each integer in this list, the engine will set up the 
  254. #            target according to the values described below, restart the target, 
  255. #            then run all test def as specified above. If you want to set up the 
  256. #            Memory Control Panel manually for one pass, leave the list empty. 
  257. #            All possible values are defined in TargetControl.lib. The most
  258. #            commonly used values are:
  259. #    
  260. #                0:    Use the custom Memory CP parameters as specified below.
  261. #                    Otherwise, those parameters are ignored.
  262. #                1:    VM on, 2x physical RAM if possible, 32-bit on.
  263. #                2:    VM off, 32-bit on.
  264. #                3:    VM on, 2x physical RAM if possible, 32-bit off.
  265. #                4:    VM off, 32-bit off.
  266. #                5:    Use random settings for all Memory CP sections.
  267. #    
  268. #        Iterate_Each_Configuration
  269. #            Use this integer to iterate configurations, with a restart in 
  270. #            between each one. You can several of the same values in the 
  271. #            Configurations__0_Is_Custom parameter also, but this allows for 
  272. #            larger numbers of repetitions. 
  273. #    
  274. #        Disk_Cache
  275. #            Custom value for the Disk Cache section of the Memory Control 
  276. #            Panel. Possible values are:
  277. #                'xK':            (x > 0) the value in KB
  278. #                'random':        choose randomly from all possible values
  279. #                'no change':    recover from Use Defaults (not implemented)
  280. #                '':                empty string to ignore this section
  281. #    
  282. #        Modern_Memory_Manager
  283. #            Custom value for the Modern Memory Manager section of the 
  284. #            Memory Control Panel. Possible values are:
  285. #                'on':            click On if not already selected
  286. #                'off':            click Off if not already selected
  287. #                'random':        click On or Off randomly
  288. #                'no change':    recover from Use Defaults (not implemented)
  289. #                '':                empty string to ignore this section
  290. #    
  291. #        _32Bit_Addressing
  292. #            Custom value for the 32-Bit Addressing section of the 
  293. #            Memory Control Panel. Possible values are:
  294. #                'on':            click On if not already selected 
  295. #                'off':            click Off if not already selected
  296. #                'random':        click On or Off randomly
  297. #                'no change':    recover from Use Defaults (not implemented)
  298. #                '':                empty string to ignore this section
  299. #    
  300. #        Virtual_Memory
  301. #            Custom value for the Virtual Memory section of the 
  302. #            Memory Control Panel. Possible values are:
  303. #                'on':            click On if not already selected
  304. #                'xM':            (x > 0) click On, set the value to xM
  305. #                'x%':            (0 <= x <= 100) click On, set to x% of maximum
  306. #                'off':            click Off if not already selected
  307. #                'min':            set to minimum (available built-in memory + 1M)
  308. #                'max':          set to maximum (available on disk - 1M)
  309. #                'auto':         turn VM off then on after setting the other 
  310. #                                    sections, and let Memory CP choose the value
  311. #                'random':        choose randomly from minimum to maximum
  312. #                'no change':    recover from Use Defaults (not implemented)
  313. #                '':                empty string to ignore this section
  314. #    
  315. #        RAM_Disk
  316. #            Custom value for the RAM Disk section of the Memory Control Panel. 
  317. #            The RAM Disk must be empty to change its settings.
  318. #            Possible values are:
  319. #                'xK':            (0 <= x) size in KB (click On or Off as needed)
  320. #                'x%':            (0 <= x <= 100) set to % of slider positions 
  321. #                                    (faster, less accurate)
  322. #                'x%!':            (0 <= x <= 100) set to % of max - min 
  323. #                                    (slower, more accurate)
  324. #                'off':            click Off
  325. #                'min':            set to minimum size
  326. #                'max':            set to maximum size
  327. #                'random':        choose randomly from all slider positions
  328. #                                    (1/125 chance of turning it off)
  329. #                'VMOn':         set size just high enough to allow use of VM 
  330. #                                    (not implemented)
  331. #                'no change':     recover from Use Defaults (not implemented)
  332. #                '':                empty string to ignore this section
  333. #    
  334. #        Use_Defaults
  335. #            Custom value for the Use Defaults section of the Memory Control 
  336. #            Panel. Possible values are:
  337. #                'click':        click Use Defaults before setting other sections
  338. #                '':                ignore this section
  339. #        Printer_Selections
  340. #            Currently all test defs assume there is a valid type of printer  
  341. #            selected. This list contains the default types. A printer selection is
  342. #            a list containing two items:
  343. #                { printerType,{ setupParameters } }
  344. #            The format of these items is defined in the file TargetControl.lib, in the 
  345. #            task SelectPrinter().
  346. #    
  347. #    MISCELLANEOUS
  348. #    This section contains miscellaneous script settings which are most useful when developing 
  349. #    and debugging test defs. Some of them eliminate much of the time taken to set up the target, 
  350. #    and allow you to skip all the fluff and jump directly to the engine itself.
  351. #    
  352. #        Verbosity_Level
  353. #            This is an integer specifying how much diagnostic information 
  354. #            you want to print in the Notebook. Possible values are:
  355. #                0:     no output except for Not-Tested-List
  356. #                1:    only Begin/End tests, Errors, Not-Tested-List and summaries
  357. #                2:    run-time output, without specifying multiple verifications
  358. #                3:     run-time output, with multiple verifications
  359. #                4:     scripter's debugging-level output
  360. #                5:     Clouseau-libs level debugging-output
  361. #            This script normally executes at verbosity level 2. The engine 
  362. #            will use level 3 for the output of any failed test def, to provide
  363. #            regression information.
  364. #    
  365. #        Use_Development_TDs
  366. #            A Boolean value that is normally false. If it is true, the engine
  367. #            will execute the test defs contained in the Dev Launchquits 
  368. #            library, which allows you to create and use new test defs
  369. #            without modifying the production libraries. Values are:
  370. #                true:    Use the development test defs in 'Dev Launchquits'
  371. #                false:    Use the standard test defs in 'LaunchQuit Test Defs.vulib'
  372. #    
  373. #        Log_Target_Info
  374. #            A Boolean value that determines whether you want the script to 
  375. #            print the current target information first, before configuring
  376. #            the target and calling the engine. Possible values are:
  377. #                true:     The engine will log the state of the target before 
  378. #                        as well as after changing the configuration. This is 
  379. #                        slower but more thorough. 
  380. #                false:    The engine will log the state of the target only after 
  381. #                        changing the configuration. This is faster.
  382. #    
  383. #        Skip_Target_Setup
  384. #            A Boolean value that determines whether to configure the target
  385. #            according to the Configurations__0_Is_Custom parameter. Possible
  386. #            values are:
  387. #                true:     The script will skip the target setup and go directly 
  388. #                        to running the test defs. This is desirable if you 
  389. #                        are developing new test defs. The script prints a 
  390. #                        list of what was not set up in the Notebook.
  391. #                false:    The engine will set up the target according to the 
  392. #                        parameters above. This is the usual setting, but you
  393. #                        can also use it for development if you want to try
  394. #                        the new test defs under various configurations.
  395. #    
  396. #        Use_MacsBug_Log_Macro
  397. #            This Boolean parameter determines whether you want to set the 
  398. #            MacsBug EveryTime macro. This macro executes automatically 
  399. #            whenever the target enters MacsBug. See the MacsBug manual for
  400. #            details. Possible values for this parameter are:
  401. #                true:    The script creates a MacsBug EveryTime macro as 
  402. #                        defined in the MacsBug_Log_Macro parameter below. 
  403. #                        After every test def and every crash, the engine 
  404. #                        checks for a MacsBug log, and if found, renames it
  405. #                        and moves it to a folder on the target startup disk.
  406. #                        If you want to ensure there is no EveryTime macro, set 
  407. #                        this parameter to true and set the MacsBug_Log_Macro
  408. #                        parameter to 'clear'.
  409. #                false:    The script will completely ignore the EveryTime macro.
  410. #                        If it is defined in the Debugger Prefs file in the 
  411. #                        target system folder, it will execute from there.
  412. #    
  413. #        MacsBug_Log_Macro
  414. #            If you put a string in this parameter consisting of valid MacsBug
  415. #            commands followed by semi-colons, and the Use_MacsBug_Log_Macro 
  416. #            parameter is set to true, the script will set up the EveryTime 
  417. #            Macro to create a log, execute the commands you put here, close 
  418. #            the log and restart. If you want to define the macro in the 
  419. #            Debugger Prefs file, put a false value in Use_MacsBug_Log_Macro.
  420. #            To ensure the EveryTime macro is cleared under all circumstances,
  421. #            put true into Use_MacsBug_Log_Macro and put 'clear' in this
  422. #            parameter. Then crashed targets will sit right where 
  423. #            they crashed. This is good for manual debugging. Possible values
  424. #            for this parameter are:
  425. #                theMacro:    A string of valid MacsBug commands, each followed 
  426. #                            by a semi-colon. For example, the string 
  427. #                            'ap;how;wh;ip;td;' will put the application name,
  428. #                            how it crashed, where it crashed, some disassembly
  429. #                            around the crash point, and the registers, into the
  430. #                            log. The commands you specify here are wrapped in 
  431. #                            commands to open a log, close it and restart, so 
  432. #                            you do not have worry about that  if you use this 
  433. #                            mechanism to make the macro. 
  434. #                            
  435. #                            If you put an empty string here, the engine will 
  436. #                            still create a log and restart, but it will be an
  437. #                            empty file.
  438. #                            
  439. #                            CAUTION: Keep it short, MacsBug is unforgiving 
  440. #                            for long macros. Also, beware of commands that
  441. #                            produce so many output lines that MacsBug asks for
  442. #                            a key press to continue auto-scrolling. Stack
  443. #                            crawls based on A7 tend to produce too much.
  444. #                'clear':     This is a special value to clear the EveryTime 
  445. #                            macro. Even if the macro is defined in the Debugger
  446. #                            Prefs file, it is cleared until the next startup.
  447. #    
  448. #        Quit_All_First
  449. #            You may want to run the LaunchQuit engine with an application 
  450. #            running in the background, or perhaps several. Normally, the
  451. #            script tries to quit all applications except Finder before 
  452. #            calling the engine. This Boolean parameter allows you to skip
  453. #            that process. Possible values are:
  454. #                true:     The script will try to quit all applications before 
  455. #                        starting the engine. This is slower but ensures there 
  456. #                        are no leftover applications taking up space. 
  457. #                false:    The script will ignore whatever applications were 
  458. #                        running at the time it started. 
  459. #                        
  460. #                        CAUTION: These applications will stay in the background 
  461. #                        for the whole run, but in the current implementation 
  462. #                        they are not re-launched after a crash.
  463. #    
  464. #        Make_Aliases
  465. #            When the script configures the target with several Control Panels, 
  466. #            you can speed up the process by allowing it to create aliases 
  467. #            and move them to the Apple Menu Items folder. When the script
  468. #            tries to open a Control Panel it looks first for the alias.
  469. #            Possible values are:
  470. #                true:     The script will create an alias for all Control Panels 
  471. #                        used during the run, and put the alias in the Apple 
  472. #                        Menu Items folder.
  473. #                        
  474. #                        CAUTION: In the current implementation the aliases
  475. #                        are not removed after the run is complete.
  476. #                false:    The script will not create an alias for Control Panels. 
  477. #    
  478. #    #        #Radar 1274935: removed Custom_Testing parameter
  479. #    #        Custom_Testing
  480. #    #            (Not implemeted well enough for production use).
  481. #    #            This Boolean value specifies if you want to execute the custom
  482. #    #            task defined in the LQCustom.lib. You can define this task
  483. #    #            any way you want. When the launch sequence is complete for 
  484. #    #            each application, the engine executes the custom task. 
  485. #    #            After the custom task returns successfully, the engine attempts 
  486. #    #            to quit the application normally. Possible values are:
  487. #    #                true:     The engine will execute the custom task.
  488. #    #                false:    The script will not execute the custom task. 
  489. #    #    
  490. #    #        #Radar 1274936: removed Use_Arbitrator_If_Available parameter
  491. #    #        Use_Arbitrator_If_Available
  492. #    #            If the Arbitrator script is running, connect to it and
  493. #    #            use it to keep track of which test def is currently 
  494. #    #            executing, and also to prevent multiple launching of
  495. #    #            applications that check for serial number conflicts
  496. #    #            over the network. Possible values are:
  497. #    #                true:     Connect to the Arbitrator if it is running.
  498. #    #                false:    Do not connect to the Arbitrator. 
  499. #    #            
  500. #    Returns:        Nothing
  501. #    Examples:        LaunchQuit();        # too much stuff for a good example
  502. #    Assumptions:    1) MUST USE VU 2.1.1
  503. #                    2) CloseView is removed entirely and never used, otherwise cmd-opt-O
  504. #                    and cmd-shift-opt-upArrowKey will not work. These are used to launch 
  505. #                    applications in the Finder and locate the startup volume, respectively.
  506. #∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
  507. #    History:
  508. #        12/20/92    SBR                Created
  509. #        06/17/94    Gary Kratzer    Added PPC launch parameter
  510. #        08/03/95    SBR        Radar 1274932:    print all parameters for ISO compliance
  511. #                            Radar 1274933:    better defaults if Use_Development_TDs := true
  512. #                            Radar 1274934:    added "PDD Maker GX" printer selection
  513. #                            Radar 1274935:    removed Custom_Testing parameter
  514. #                            Radar 1274936:    removed Use_Arbitrator_If_Available parameter
  515. #        08/27/96    BRL        Radar 1379278:    removed onTarget calls
  516. #                            Radar 1352263:    removed fileTool version checks
  517. #                            Changed some parameter defaults
  518. #        09/27/96    BRL        Added SPEC Exception handling
  519. #########################################################################
  520. script LaunchQuit
  521. (
  522.     Print_Instructions := false,
  523.     Run_Title := "LaunchQuit Engine 2.1.4 Test Run",
  524.     Report_To_Phoenix := false,
  525.     ________________________ := "_________________________",
  526.     Test_Type := 1,
  527.     Skip_These_Tests := { "testNameHerePartialNameOK" },
  528.     Run_Only_These_Tests := { "testNameHerePartialNameOK" },
  529.     Iterate_Each_Test := 1,
  530.     Random_Order_Once_Each := false,
  531.     Random_Seed := 0,
  532.     Launch_Method := "auto",
  533.     Special_Parameters := { "exactSpellingRequired" },
  534.     Resume_Last_Run := false,
  535.     Resume_Offset := 1,
  536.     _______________________ := "_________________________",
  537.     Configurations__0_Is_Custom := { (*1,2*) },    #see TargetControl.lib for pre-set values
  538.     Iterate_Each_Configuration := 1,
  539.     Disk_Cache := "",
  540.     Modern_Memory_Manager := "",
  541.     _32Bit_Addressing := "",
  542.     Virtual_Memory := "",
  543.     RAM_Disk := "Off",
  544.     Use_Defaults := "click",
  545.     Printer_Selections := {{"LaserWriter 8",{}},{"LaserWriter",{}},{"PDD Maker GX",{}}},
  546.     #Screen_Depth := 8,
  547.     #Gray_Scale := false,
  548.     #_68040_Cache := true,
  549.     ______________________ := "_________________________",
  550.     Verbosity_Level := 2,
  551.     Use_Development_TDs := false,
  552.     Log_Target_Info := true,
  553.     Skip_Target_Setup := false,
  554.     Use_MacsBug_Log_Macro := true,
  555.     MacsBug_Log_Macro := "ap;how;wh;ip;td;",        (*stdlog*)
  556.     _____________________ := "_________________________",
  557.     Quit_All_First := true,
  558.     Make_Aliases := false
  559. #    Custom_Testing := false,
  560. )
  561.  
  562. begin
  563.     global gDevelopmentMode;
  564.     
  565.     trace( false );
  566.     
  567.     println; println; 
  568.     println 'LaunchQuit Engine 2.1.4';
  569.     println 'Copyright ©Apple Computer, Inc. 1992-1997';
  570.     println; 
  571. #    println '••••••SPECIAL FOREGROUND VS BACKGROUND RUN•••••••••••';
  572.     
  573.     if Print_Instructions
  574.     begin
  575.         printLQInstructions();
  576.         exit;
  577.     end;
  578.     
  579.     CommandExceptions(true);
  580.  
  581.     try
  582.         match[target t:?tName];
  583.     catch theError
  584.         tName := undefined;
  585.     
  586.     if tName
  587.         actorName(tName);
  588.     else 
  589.     begin
  590.         SysBeep();
  591.         println;     println;     println;     println;     println; 
  592.         println (*You Idiot!*) "No target selected, or target crashed at run time.";
  593.         exit;
  594.     end;
  595.     
  596.     InitGlobals();
  597.     
  598.     CommandTimeOut(121);        #SBR 08/27/94: No retries in VU 2.1. Set to 121 seconds (ADSP timeout + 1).
  599.     ExternalToolTimeout(999);    #SBR 08/27/94: External Tools TimeOut in VU 2.1; Set to 121 seconds.
  600.     maxFailures(32766);
  601.     mouseSpeed(50);                #SBR 08/27/94: Went from 0 (instant) to 50 (smooth, fast speed).
  602.     
  603.     RPushVerbosity(Verbosity_Level);
  604.  
  605.     AddExceptionHandler(-1100, {TASK EH_CrashRecover, {'LaunchQuit Script.vu',1,5},0});
  606.     AddExceptionHandler(-1104, {TASK EH_CrashRecover, {'LaunchQuit Script.vu',1,5},0});
  607.     AddExceptionHandler(-1105, {TASK EH_CrashRecover, {'LaunchQuit Script.vu',1,5},0});
  608.  
  609.     println 'Run Name: ', Run_Title;
  610.     println 'Target: ', tName;
  611.     
  612.     theTime := _Match([time]);
  613.     
  614.     println 'Date: ', theTime.m, '/', theTime.d, '/', theTime.y;
  615.     theHour := theTime.h;
  616.     if theHour >= 1200 and theHour < 2400
  617.         theM := 'PM';
  618.     else 
  619.         theM := 'AM';
  620.     if theHour > 1259
  621.         theHour := theHour - 1200;
  622.     if theHour < 100 
  623.         theHour := theHour + 1200;
  624.     theHour := "{theHour}";
  625.     if card theHour < 4                # make it pretty
  626.         theTime := theHour[1] + ':' + theHour[2] + theHour[3];
  627.     else 
  628.         theTime := theHour[1] + theHour[2] + ':' + theHour[3] + theHour[4];
  629.     println 'Time: ', theTime, ' ', theM;
  630.     println; 
  631.     
  632.     if Use_Development_TDs
  633.     begin
  634.         # added for Radar 1274933
  635.         println "YOU ARE IN DEVELOPMENT MODE. ";
  636.         println "    Log_Target_Info := false";
  637.         println "    Skip_Target_Setup := true";
  638.         println;
  639.         gDevelopmentMode := true;
  640.         Log_Target_Info := false;
  641.         Skip_Target_Setup := true;
  642.     end;
  643.     else
  644.     begin
  645.         gDevelopmentMode := false;
  646.     end;
  647.         
  648.     #(    Print all parameters for ISO compliance, Radar 1274932
  649.     if not gDevelopmentMode
  650.     begin
  651.         println "SCRIPT PARAMETERS ••••••••••••••••••••••••••••••••••••••••••••••";
  652.         println "Print_Instructions: {Print_Instructions}";
  653.         println "Run_Title: ∂"{Run_Title}∂"";
  654.         println "Report_To_Phoenix: {Report_To_Phoenix}";
  655.         println "Test_Type: {Test_Type}";
  656.         println "Skip_These_Tests: {Skip_These_Tests}";
  657.         println "Run_Only_These_Tests: {Run_Only_These_Tests}";
  658.         println "Iterate_Each_Test: {Iterate_Each_Test}";
  659.         println "Random_Order_Once_Each: {Random_Order_Once_Each}";
  660.         println "Random_Seed: {Random_Seed}";
  661.         println "Launch_Method: ∂"{Launch_Method}∂"";
  662.         println "Special_Parameters: {Special_Parameters}";
  663.         println "Resume_Last_Run: {Resume_Last_Run}";
  664.         println "Resume_Offset: {Resume_Offset}";
  665.         println "_______________________: {_______________________}";
  666.         println "Configurations__0_Is_Custom: {Configurations__0_Is_Custom}";
  667.         println "Iterate_Each_Configuration: {Iterate_Each_Configuration}";
  668.         if Configurations__0_Is_Custom 
  669.         begin
  670.             println "Disk_Cache: ∂"{Disk_Cache}∂"";
  671.             println "Modern_Memory_Manager: ∂"{Modern_Memory_Manager}∂"";
  672.             println "_32Bit_Addressing: ∂"{_32Bit_Addressing}∂"";
  673.             println "Virtual_Memory: ∂"{Virtual_Memory}∂"";
  674.             println "RAM_Disk: ∂"{RAM_Disk}∂"";
  675.             println "Use_Defaults: ∂"{Use_Defaults}∂"";
  676.         end;
  677.         println "Printer_Selections: {Printer_Selections}";
  678.         #println "Screen_Depth: {Screen_Depth}";
  679.         #println "Gray_Scale: {Gray_Scale}";
  680.         #println "_68040_Cache: {_68040_Cache}";
  681.         println "______________________: {______________________}";
  682.         println "Verbosity_Level: {Verbosity_Level}";
  683.         println "Use_Development_TDs: {Use_Development_TDs}";
  684.         println "Log_Target_Info: {Log_Target_Info}";
  685.         println "Skip_Target_Setup: {Skip_Target_Setup}";
  686.         println "Use_MacsBug_Log_Macro: {Use_MacsBug_Log_Macro}";
  687.         println "MacsBug_Log_Macro: ∂"{MacsBug_Log_Macro}∂"";
  688.         println "_____________________: {_____________________}";
  689.         println "Quit_All_First: {Quit_All_First}";
  690.         println "Make_Aliases: {Make_Aliases}";
  691.         println "••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••";
  692.         println;
  693.     end;    
  694.     #)    End printing all parameters
  695.  
  696.     if Log_Target_Info and not Resume_Last_Run        # do not log target info for a resume
  697.         info_v_level  := 1;
  698.     else 
  699.         info_v_level  := 6;
  700.  
  701.     if Random_Seed 
  702.     begin
  703.         randomSeed(Random_Seed);
  704.         RStatus("RandomSeed was set to {randomSeed()} for reproducibility.",2);
  705.     end;
  706.  
  707.     if not Skip_Target_Setup
  708.     begin
  709.         CheckExternalToolVersions();
  710.     end;
  711.     
  712.     reset_target_info(info_v_level < 6, info_v_level);    # Gets CPU info, prints it if desired
  713.     
  714.     if not Skip_Target_Setup
  715.     begin
  716.         if Quit_All_First
  717.         begin
  718.             quit_apps({},true);                        # quit all applications
  719.             key_eq('w',5);
  720.         end;
  721.         
  722.         if Printer_Selections
  723.         begin
  724.             if not SelectPrinter(Printer_Selections)
  725.             begin
  726.                 RError("Could not select a printer!!? Exiting script",1);
  727.                 exit;
  728.             end;
  729.         end;
  730.         
  731.         if isMember(Launch_Method, {'VUAidFKEY'})
  732.         begin
  733.             SysBeep();
  734.             RStatus("VUAidFKEY is an obsolete launch method");
  735.             RStatus("Please choose a different launch method. Exiting LaunchQuit Script.vu...");
  736.             exit;
  737.         end;
  738.  
  739.         if Make_Aliases or not _MatchBoolean([menuItem t:/Memory≈/ m:1],true)
  740.             alias_control_panel('Memory');
  741.  
  742.         MacsBugLog('delete');
  743.         if Use_MacsBug_Log_Macro                    # stored macro is undefined if ignored (NOT cleared)
  744.             SetMacsBugMacro(MacsBug_Log_Macro);        
  745.     end;
  746.     else 
  747.     begin
  748.         println;
  749.         println "Skipping target setup - the following features are disabled:";
  750.         println "Quit_All_First, Select_Printer, Make_Memory_Alias, "; 
  751.         println "Target_Control, SetMacsBugMacro and CheckExternalToolVersions.";
  752.         println ;
  753.         #println "Some test defs may not work properly because the target information ";
  754.         #println "is incomplete. If you want a full run but do not want the script to change ";
  755.         #println "the control panels, put an empty list, ∂{∂}, into Configurations__0_Is_Custom.";
  756.         #println;
  757.  
  758.         Configurations__0_Is_Custom := {};
  759.     end;
  760.     
  761.     engineParameters := {};
  762.     if Use_Development_TDs                         # refer to "Dev LaunchQuits"
  763.     begin
  764.         engineParameters := engineParameters + {{ 'GetTestDefTask',task GetDevLaunchQuitTD }};
  765.         println "You set the Use_Development_TDs script parameter to true, so the";
  766.         println "LaunchQuit Engine will use the Development test defs.";
  767.         println ;
  768.     end;
  769.     else                                            # refer to "LaunchQuit Test Defs.vulib"
  770.         engineParameters := engineParameters + {{ 'GetTestDefTask',task GetLaunchQuitTD }};
  771.     
  772.     if Use_Arbitrator_If_Available
  773.         engineParameters := engineParameters + {'UsingArbitrator'};
  774.         
  775.     if Resume_Last_Run
  776.     begin
  777.         if Resume_Last_Run[card Resume_Last_Run] <> '@'        # user specified a partial name
  778.             Resume_Last_Run := /≈{Resume_Last_Run}≈/;
  779.             
  780.         engineParameters := engineParameters + {{ 'resumeThisTD',Resume_Last_Run }};
  781.         
  782.         # store the index of the resume item for later removal, part of fix for Radar 1119461
  783.         resumeThisTDIndex := card engineParameters;            
  784.         
  785.         engineParameters := engineParameters + {{ 'resumeTDOffset',Resume_Offset }};
  786.     end;
  787.     else 
  788.         engineParameters := engineParameters + {{ 'resume','Reset' }};
  789.     
  790.     Time_Formats := { 'TDCore' };                    # see LaunchQuits.lib for choices
  791.     if Time_Formats
  792.         engineParameters := engineParameters + {{'timers', Time_Formats}};
  793.     
  794.     engineParameters := engineParameters + {{ 'Phoenix', Report_To_Phoenix }};
  795.  
  796.     engineParameters := engineParameters + {{ 'launchBy', Launch_Method }};
  797.     engineParameters := engineParameters + {{ 'iterateTD', Iterate_Each_Test }};
  798.     
  799.     temp := isMember('exactSpellingRequired', Special_Parameters);
  800.     if temp 
  801.         Special_Parameters := remove( temp, Special_Parameters );
  802.     engineParameters := engineParameters + {{'specialParameters', Special_Parameters}};
  803.     
  804.     engineParameters := engineParameters + {{'randomDeal', Random_Order_Once_Each}};
  805.     engineParameters := engineParameters + {{'doCustomTask', Custom_Testing}};
  806.     
  807.     temp := isMember('testNameHerePartialNameOK', Run_Only_These_Tests);
  808.     if temp 
  809.         Run_Only_These_Tests := remove( temp, Run_Only_These_Tests );
  810.     
  811.     temp := isMember('testNameHerePartialNameOK', Skip_These_Tests);
  812.     if temp 
  813.         Skip_These_Tests := remove( temp, Skip_These_Tests );
  814.     
  815.     if not Configurations__0_Is_Custom
  816.     begin
  817.         for thisIteration := 1 to Iterate_Each_Configuration
  818.         begin
  819. #                if Iterate_Each_Configuration > 1
  820. #                begin
  821. #                    if (thisIteration mod 2) = 1
  822. #                    begin
  823. #                        launch ('VUsr', false, true);
  824. #                        RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} IN FOREGROUND");
  825. #                    end;
  826. #                    else
  827. #                    begin
  828. #                        launch ('MPS ', false, true);
  829. #                        RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} IN BACKGROUND");
  830. #                    end;
  831. #                end;
  832.             if Iterate_Each_Configuration > 1
  833.                 RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} FOR MANUAL MODE");
  834.             CheckLaunchQuit( Test_Type, Run_Only_These_Tests, Skip_These_Tests, engineParameters);
  835.             if Resume_Last_Run        #remove resume parameters after 1st pass, fixes Radar 1119461
  836.             begin
  837.                 engineParameters := remove(resumeThisTDIndex + 1,engineParameters);    #highest first
  838.                 engineParameters := remove(resumeThisTDIndex,engineParameters);
  839.             end;
  840.         end;
  841.     end;
  842.     else for each theMode in Configurations__0_Is_Custom
  843.     begin
  844.         for thisIteration := 1 to Iterate_Each_Configuration
  845.         begin
  846.             if Iterate_Each_Configuration > 1
  847.             begin
  848.                 if Iterate_Each_Configuration > 1
  849.                     RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} FOR MODE {theMode}");
  850.  
  851. #                    if (thisIteration mod 2) = 1
  852. #                    begin
  853. #                        launch ('VUsr', false, true);
  854. #                        RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} IN FOREGROUND MODE {theMode}");
  855. #                    end;
  856. #                    else
  857. #                    begin
  858. #                        launch ('MPS ', false, true);
  859. #                        RStatus("BEGIN LAUNCHQUIT ENGINE ITERATION #{thisIteration} IN BACKGROUND MODE {theMode}");
  860. #                    end;
  861.             end;
  862.             if theMode
  863.                 target_control(theMode,,info_v_level);
  864.             else 
  865.                 target_control    
  866.                 (    0,
  867.                     {
  868.                         { 'dc',Disk_Cache},
  869.                         { 'mm',Modern_Memory_Manager},
  870.                         { 'vm',Virtual_Memory},
  871.                         { '32',_32Bit_Addressing},
  872.                         { 'rd',RAM_Disk},
  873.                         { 'ud',Use_Defaults},
  874.                         'quick'
  875.                         #{ 'bd',Screen_Depth},
  876.                         #{ 'gs',Gray_Scale},
  877.                         #{ '40',_68040_Cache}
  878.                     },
  879.                     info_v_level
  880.                 );
  881.             
  882.             # 02/19/94 SBR: Moved VUAid availability check to beginning of script. 
  883.             
  884.             CheckLaunchQuit( Test_Type, Run_Only_These_Tests, Skip_These_Tests, engineParameters);
  885.             if Resume_Last_Run        #remove resume parameters after 1st pass, fixes Radar 1119461
  886.             begin
  887.                 engineParameters := remove(resumeThisTDIndex + 1,engineParameters);    #highest first
  888.                 engineParameters := remove(resumeThisTDIndex,engineParameters);
  889.             end;
  890.         end;
  891.     end;
  892.     
  893.     RemoveExceptionHandler(-1105);
  894.     RemoveExceptionHandler(-1104);
  895.     RemoveExceptionHandler(-1100);
  896.     sysBeep();
  897. end;
  898.  
  899.  
  900. #########################################################################
  901. #    task                    PrintLQInstructions()
  902. #∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
  903. #    Description:    Prints the instructions for the script parameters for the 
  904. #                    LaunchQuit engine.
  905. #    Parameters:        none
  906. #    Returns:        nothing  
  907. #    Examples:        PrintLQInstructions();
  908. #    Assumptions:    None
  909. #∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
  910. #    History:
  911. #        09/07/94    SBR            Created
  912. #        08/03/95    SBR            Added Printer_Selections instructions
  913. #        01/10/97    SBR            Updated for LQ Engine 2.1.1
  914. #        04/10/97    SBR            Updated for LQ Engine 2.1.4
  915. #########################################################################
  916. task PrintLQInstructions()
  917. begin 
  918.     println "INSTRUCTIONS FOR THE LAUNCHQUIT ENGINE 2.1.4";
  919.     println "Copyright © Apple Computer, Inc. 1994-1997";
  920.     println "";
  921.     println "These are instructions on how to use the LaunchQuit engine script parameters.";
  922.     println "Press command-period any time to stop. To prevent printing the instructions,";
  923.     println "set the Print_Instructions script parameter to false.";
  924.     println "";
  925.     println "";
  926.     println "    Print_Instructions";
  927.     println "        Possible values are:";
  928.     println "            true:    Print the instructions for how to use the script parameters, ";
  929.     println "                    then exit the script.";
  930.     println "            false:    Execute the script normally. Do not print instructions.";
  931.     println "";
  932.     println "    Run_Title";
  933.     println "        This is just a string the engine puts into the notebook as an ";
  934.     println "        identifier for someone reading the log later. It can be anything ";
  935.     println "        you want. For example, you might use ";
  936.     println "        'Quadra 840AV GMc4 Acceptance Launchquits with EtherNet'.";
  937.     println "";
  938.     println "    Report_To_Phoenix";
  939.     println "        This is a Boolean to switch on and off TCS reporting to Phoenix from ";
  940.     println "        the LaunchQuit Engine. For a description of TCS reporting, refer to ";
  941.     println "        the HitchHiker's Guide to SPEC S&L.";
  942.     println "            true:     report test def results to a Phoenix database";
  943.     println "                    through the Results Express external tool";
  944.     println "            false:     do not report test def results externally";
  945.     println "";
  946.     println "TEST DEF SELECTION";
  947.     println "This section allows you to specify which test defs you want to execute and how to ";
  948.     println "execute them. It partains to the method of launching, a switch for randomness, and how";
  949.     println "to resume from stopping in the middle of the script.";
  950.     println "";
  951.     println "    Test_Type";
  952.     println "        The type of test you want to run, similar to the tier for ";
  953.     println "        application compatibility testing. Test defs can be divided into ";
  954.     println "        types 1, 2, and 3, with type 1 being the kind you want to run every ";
  955.     println "        time, and 3 the kind you want to run least often. Currently, all ";
  956.     println "        Launchquits are type 1.";
  957.     println "";
  958.     println "    Skip_These_Tests";
  959.     println "        A list of test defs never to use under any circumstances. Include ";
  960.     println "        the string or regular expression name(s) of the application(s) you ";
  961.     println "        want to skip for this run of the engine. They will be logged as ";
  962.     println "        Incomplete tests in the Notebook. The name can be partial, but only ";
  963.     println "        the first occurrance counts. The items are removed from the list as ";
  964.     println "        they are skipped. If the name does not end in '@' then it is assumed ";
  965.     println "        to be a partial name and a trailing '≈' is added. For example: ";
  966.     println "        ∂{ ∂/≈PageMaker≈∂/, 'Adobe Premiere' ∂} will skip these two and run all ";
  967.     println "        others. This parameter overides all others.";
  968.     println "";
  969.     println "    Run_Only_These_Tests";
  970.     println "        A list of test defs to test, if you want to use a subset. Include ";
  971.     println "        the string or regular expression name(s) of the application(s) you ";
  972.     println "        want to test during this run of the engine. If there are any items in ";
  973.     println "        this list the engine will use ONLY the listed test defs. The other ";
  974.     println "        applications are ignored and not logged. This is most useful for ";
  975.     println "        iterating a specific test def for regression. The name can be ";
  976.     println "        partial, but only the first occurance will be executed. The items are ";
  977.     println "        removed from the list as they are used. If the name does not end in ";
  978.     println "        '@' then it is assumed to be a partial name and a trailing '≈' is ";
  979.     println "        added. For example: ∂{ ∂/≈PageMaker≈∂/, 'Adobe Premiere' ∂} will run ";
  980.     println "        ONLY these two.";
  981.     println "";
  982.     println "        NOTE: If the same name is in Skip_These_Tests and Run_Only_These_Tests, ";
  983.     println "        then the request to skip takes priority over the request to run.";
  984.     println "";
  985.     println "    Iterate_Each_Test";
  986.     println "        An integer specifying how many times to iterate each test def ";
  987.     println "        which is not skipped. This parameter is useful for stress testing.";
  988.     println "";
  989.     println "    Random_Order_Once_Each";
  990.     println "        Changes the order of execution. The engine will execute all test ";
  991.     println "        defs in pseudo-random order, but none will execute more than once, ";
  992.     println "        unless Iterate_Each_Test is greater than one. Possible values are:";
  993.     println "            true:    Test defs execute in pseudo-random order.";
  994.     println "            false:    Test defs execute in natural order, which is alphabetic.";
  995.     println "";
  996.     println "    Random_Seed";
  997.     println "        Used when trying to reproduce pseudo-random tests. Before using VU's";
  998.     println "        random number generator, the script prints the random seed in the ";
  999.     println "        Notebook. If you want to reproduce a test run then copy the seed from ";
  1000.     println "        the Notebook and paste it in this parameter. Possible values are:";
  1001.     println "            zero:        Allow VU create a new random seed.";
  1002.     println "            integer:    Set the random seed to the specified value.";
  1003.     println "";
  1004.     println "    Launch_Method";
  1005.     println "        This allows you to specify how you want to launch the application. ";
  1006.     println "        The most reliable method is 'Finder'. The fastest is 'auto'.";
  1007.     println "        The possible values are:";
  1008.     println "            'AgentVUFG':    Launch by creator into the foreground using Agent VU.";
  1009.     println "                CAUTION:    Agent VU 2.0, 2.0.1, and 2.1 will not launch an app if the ";
  1010.     println "                            preferred size is not available. Since Agent VU uses ";
  1011.     println "                            the creator, that should be unique across all ";
  1012.     println "                            mounted target volumes.";
  1013.     println "            'AgentVUBG':    Launch by creator into the background using Agent VU. ";
  1014.     println "                            Since most applications do not launch properly into ";
  1015.     println "                            the background, this method is not allowed unless ";
  1016.     println "                            launchParams contains 'bgLaunchOK'.";
  1017.     println "            'Finder':        Twitch to Finder and Find appName. Type command-O ";
  1018.     println "                            while pressing the option key to close the containing window.";
  1019.     println "                            This method is slow but sure if the names are unique.";
  1020.     println "            'Find File':    Launch the Find File DA and find appName. Uses option-";
  1021.     println "                            doubleClick to quit Find File before launching the app.";
  1022.     println "                            This method is sure if the names are unique.";
  1023.     println "            'auto':            Use 'agentVUFG', but if this is fails use 'Find File'.";
  1024.     println "            'VUAid2FG':        Launch by appName into foreground using VUAid External tool.";
  1025.     println "            'VUAid2BG':        Launch by appName into background using VUAid External tool.";
  1026.     println "";
  1027.     println "    Special_Parameters";
  1028.     println "        Launch only the applications with the specified launch parameters. ";
  1029.     println "        This is mainly used to test under known failure conditions. ";
  1030.     println "        Possible values are:";
  1031.     println "            'FPU':            The application expects the target to have an FPU.";
  1032.     println "            '32Bit':        The application crashes under 32-bit addressing.";
  1033.     println "            '68040 Caches':    The application crashes if 68040 Caches are on.";
  1034.     println "            'QuickTime':    The application expects the target to have QuickTime.";
  1035.     println "            'noCreatorLaunch':    There are multiple applications across the ";
  1036.     println "                            target volumes which have this creator. ";
  1037.     println "            'bgLaunchOK':    The application can launch into the background.";
  1038.     println "                            Most apps are not made to launch into the backgound so you ";
  1039.     println "                            need to qualify each one thouroughly before allowing it.";
  1040.     println "            'SNConflict':    The application uses network-based serial number ";
  1041.     println "                            copy protection.                 ";
  1042.     println "            'PPC':            The application runs only on a PowerPC (not 68K).";
  1043.     println "            '68K':            The application runs only on a real 68K processor (very rare).";
  1044.     println "            'MMM':            The application does not launch with Modern Memory Manager on.";
  1045.     println "            'EBBE':            The application crashes with EvenBetterBusError,a system ";
  1046.     println "                                extension to help catch renegade references to NIL.";
  1047. #        println "            'MaxT0':        For Maxwell tier 0 app. Yet to be implemented.";
  1048.     println "            ∂{'bitDepth',∂{restrictedBitDepths∂}∂}∂:    The application will run only";
  1049.     println "                            if the target bitdepth is contained in the list of ";
  1050.     println "                            restricted bitdepths. For example, ∂{'bitDepth',∂{8,16,32∂}∂}.";
  1051.     println "";
  1052.     println "    Resume_Last_Run";
  1053.     println "        If for some reason you stop the Launchquit script prematurely, ";
  1054.     println "        you can resume at any application by putting its name in this ";
  1055.     println "        parameter. You can use a partial or exact name. The best way is to ";
  1056.     println "        copy the exact name of the last attempted test def from the ";
  1057.     println "        Notebook. NOTE: If you are using Run_Only_These_Tests, the string ";
  1058.     println "        in this parameter must exactly equal the string in Run_Only_These_Tests.";
  1059.     println "";
  1060.     println "    Resume_Offset";
  1061.     println "        Using this if you want to resume at some test def after the one";
  1062.     println "        specified in Resume_Last_Run. Include an integer representing the";
  1063.     println "        offset from the original. The engine will find the nth test def that";
  1064.     println "        matches Special_Parameters. For example, the last test def executed";
  1065.     println "        before you stopped the engine might be 'SimAnt'. Usually, if SimAnt ";
  1066.     println "        failed, you will want to resume at the next one, so put 'SimAnt' ";
  1067.     println "        in Resume_Last_Run and 1 into the Resume_Offset. If you want to ";
  1068.     println "        resume with 'SimAnt', use a zero here. You can not use negative ";
  1069.     println "        offsets, but the number may be as high as the number of test defs";
  1070.     println "        matching Special_Parameters.";
  1071.     println "";
  1072.     println "TARGET SETUP";
  1073.     println "This section allows you to specify how to set up the Memory Control Panel, and how many times ";
  1074.     println "you want to run through all the test defs in each configuration. To use this feature, the ";
  1075.     println "VUAid 2.1 External Tool must be on the Target.";
  1076.     println "";
  1077.     println "    Configurations__0_Is_Custom";
  1078.     println "        For each integer in this list, the engine will set up the ";
  1079.     println "        target according to the values described below, restart the target, ";
  1080.     println "        then run all test defs as specified above. If you want to set up the ";
  1081.     println "        Memory Control Panel manually for one pass, leave the list empty. ";
  1082.     println "        All possible values are defined in TargetControl.lib. The most";
  1083.     println "        commonly used values are:";
  1084.     println "";
  1085.     println "            0:    Use the custom Memory CP parameters as specified below.";
  1086.     println "                Otherwise, those parameters are ignored.";
  1087.     println "            1:    VM on, 2x physical RAM if possible, 32-bit on.";
  1088.     println "            2:    VM off, 32-bit on.";
  1089.     println "            3:    VM on, 2x physical RAM if possible, 32-bit off.";
  1090.     println "            4:    VM off, 32-bit off.";
  1091.     println "            5:    Use random settings for all Memory CP sections.";
  1092.     println "";
  1093.     println "    Iterate_Each_Configuration";
  1094.     println "        Use this integer to iterate configurations, with a restart in ";
  1095.     println "        between each one. You can several of the same values in the ";
  1096.     println "        Configurations__0_Is_Custom parameter also, but this allows for ";
  1097.     println "        larger numbers of repetitions. ";
  1098.     println "";
  1099.     println "    Disk_Cache";
  1100.     println "        Custom value for the Disk Cache section of the Memory Control ";
  1101.     println "        Panel. Possible values are:";
  1102.     println "            'xK':            (x > 0) the value in KB";
  1103.     println "            'random':        choose randomly from all possible values";
  1104.     println "            'no change':    recover from Use Defaults (not implemented)";
  1105.     println "            '':                empty string to ignore this section";
  1106.     println "";
  1107.     println "    Modern_Memory_Manager";
  1108.     println "        Custom value for the Modern Memory Manager section of the ";
  1109.     println "        Memory Control Panel. Possible values are:";
  1110.     println "            'on':            click On if not already selected";
  1111.     println "            'off':            click Off if not already selected";
  1112.     println "            'random':        click On or Off randomly";
  1113.     println "            'no change':    recover from Use Defaults (not implemented)";
  1114.     println "            '':                empty string to ignore this section";
  1115.     println "";
  1116.     println "    _32Bit_Addressing";
  1117.     println "        Custom value for the 32-Bit Addressing section of the ";
  1118.     println "        Memory Control Panel. Possible values are:";
  1119.     println "            'on':            click On if not already selected ";
  1120.     println "            'off':            click Off if not already selected";
  1121.     println "            'random':        click On or Off randomly";
  1122.     println "            'no change':    recover from Use Defaults (not implemented)";
  1123.     println "            '':                empty string to ignore this section";
  1124.     println "";
  1125.     println "    Virtual_Memory";
  1126.     println "        Custom value for the Virtual Memory section of the ";
  1127.     println "        Memory Control Panel. Possible values are:";
  1128.     println "            'on':            click On if not already selected";
  1129.     println "            'xM':            (x > 0) click On, set the value to xM";
  1130.     println "            'x%':            (0 <= x <= 100) click On, set to x% of maximum";
  1131.     println "            'off':            click Off if not already selected";
  1132.     println "            'min':            set to minimum (available built-in memory + 1M)";
  1133.     println "            'max':          set to maximum (available on disk - 1M)";
  1134.     println "            'auto':         turn VM off then on after setting the other ";
  1135.     println "                                sections, and let Memory CP choose the value";
  1136.     println "            'random':        choose randomly from minimum to maximum";
  1137.     println "            'no change':    recover from Use Defaults (not implemented)";
  1138.     println "            '':                empty string to ignore this section";
  1139.     println "";
  1140.     println "    RAM_Disk";
  1141.     println "        Custom value for the RAM Disk section of the Memory Control Panel. ";
  1142.     println "        The RAM Disk must be empty to change its settings.";
  1143.     println "        Possible values are:";
  1144.     println "            'xK':            (0 <= x) size in KB (click On or Off as needed)";
  1145.     println "            'x%':            (0 <= x <= 100) set to % of slider positions ";
  1146.     println "                                (faster, less accurate)";
  1147.     println "            'x%!':            (0 <= x <= 100) set to % of max - min ";
  1148.     println "                                (slower, more accurate)";
  1149.     println "            'off':            click Off";
  1150.     println "            'min':            set to minimum size";
  1151.     println "            'max':            set to maximum size";
  1152.     println "            'random':        choose randomly from all slider positions";
  1153.     println "                                (1/125 chance of turning it off)";
  1154.     println "            'VMOn':         set size just high enough to allow use of VM ";
  1155.     println "                                (not implemented)";
  1156.     println "            'no change':     recover from Use Defaults (not implemented)";
  1157.     println "            '':                empty string to ignore this section";
  1158.     println "";
  1159.     println "    Use_Defaults";
  1160.     println "        Custom value for the Use Defaults section of the Memory Control ";
  1161.     println "        Panel. Possible values are:";
  1162.     println "            'click':        click Use Defaults before setting other sections";
  1163.     println "            '':                ignore this section";
  1164.     println "    Printer_Selections ";
  1165.     println "        Currently all test defs assume there is a valid type of printer   ";
  1166.     println "        selected. This list contains the default types. A printer selection is ";
  1167.     println "        a list containing two items: ";
  1168.     println "            ∂{ printerType,∂{ setupParameters ∂} ∂} ";
  1169.     println "        The format of these items is defined in the file TargetControl.lib, in the  ";
  1170.     println "        task SelectPrinter(). ";
  1171.     println "";
  1172.     println "MISCELLANEOUS";
  1173.     println "This section contains miscellaneous script settings which are most useful when developing ";
  1174.     println "and debugging test defs. Some of them eliminate much of the time taken to set up the target, ";
  1175.     println "and allow you to skip all the fluff and jump directly to the engine itself.";
  1176.     println "";
  1177.     println "    Verbosity_Level";
  1178.     println "        This is an integer specifying how much diagnostic information ";
  1179.     println "        you want to print in the Notebook. Possible values are:";
  1180.     println "            0:     no output except for Not-Tested-List";
  1181.     println "            1:    only Begin/End tests, Errors, Not-Tested-List and summaries";
  1182.     println "            2:    run-time output, without specifying multiple verifications";
  1183.     println "            3:     run-time output, with multiple verifications";
  1184.     println "            4:     scripter's debugging-level output";
  1185.     println "            5:     Clouseau-libs level debugging-output";
  1186.     println "        This script normally executes at verbosity level 2. The engine ";
  1187.     println "        will use level 3 for the output of any failed test def, to provide";
  1188.     println "        regression information.";
  1189.     println "";
  1190.     println "    Use_Development_TDs";
  1191.     println "        A Boolean value that is normally false. If it is true, the engine";
  1192.     println "        will execute the test defs contained in the Dev Launchquits ";
  1193.     println "        library, which allows you to create and use new test defs";
  1194.     println "        without modifying the production libraries. Values are:";
  1195.     println "            true:    Use the development test defs in 'Dev Launchquits'";
  1196.     println "            false:    Use the standard test defs in 'LaunchQuit Test Defs.vulib'";
  1197.     println "";
  1198.     println "    Log_Target_Info";
  1199.     println "        A Boolean value that determines whether you want the script to ";
  1200.     println "        print the current target information first, before configuring";
  1201.     println "        the target and calling the engine. Possible values are:";
  1202.     println "            true:     The engine will log the state of the target before ";
  1203.     println "                    as well as after changing the configuration. This is ";
  1204.     println "                    slower but more thorough. ";
  1205.     println "            false:    The engine will log the state of the target only after ";
  1206.     println "                    changing the configuration. This is faster.";
  1207.     println "";
  1208.     println "    Skip_Target_Setup";
  1209.     println "        A Boolean value that determines whether to configure the target";
  1210.     println "        according to the Configurations__0_Is_Custom parameter. Possible";
  1211.     println "        values are:";
  1212.     println "            true:     The script will skip the target setup and go directly ";
  1213.     println "                    to running the test defs. This is desirable if you ";
  1214.     println "                    are developing new test defs. The script prints a ";
  1215.     println "                    list of what was not set up in the Notebook.";
  1216.     println "            false:    The engine will set up the target according to the ";
  1217.     println "                    parameters above. This is the usual setting, but you";
  1218.     println "                    can also use it for development if you want to try";
  1219.     println "                    the new test defs under various configurations.";
  1220.     println "";
  1221.     println "    Use_MacsBug_Log_Macro";
  1222.     println "        This Boolean parameter determines whether you want to set the ";
  1223.     println "        MacsBug EveryTime macro. This macro executes automatically ";
  1224.     println "        whenever the target enters MacsBug. See the MacsBug manual for";
  1225.     println "        details. Possible values for this parameter are:";
  1226.     println "            true:    The script creates a MacsBug EveryTime macro as ";
  1227.     println "                    defined in the MacsBug_Log_Macro parameter below. ";
  1228.     println "                    After every test def and every crash, the engine ";
  1229.     println "                    checks for a MacsBug log, and if found, renames it";
  1230.     println "                    and moves it to a folder on the target startup disk.";
  1231.     println "                    If you want to ensure there is no EveryTime macro, set ";
  1232.     println "                    this parameter to true and set the MacsBug_Log_Macro";
  1233.     println "                    parameter to 'clear'.";
  1234.     println "            false:    The script will completely ignore the EveryTime macro.";
  1235.     println "                    If it is defined in the Debugger Prefs file in the ";
  1236.     println "                    target system folder, it will execute from there.";
  1237.     println "";
  1238.     println "    MacsBug_Log_Macro";
  1239.     println "        If you put a string in this parameter consisting of valid MacsBug";
  1240.     println "        commands followed by semi-colons, and the Use_MacsBug_Log_Macro ";
  1241.     println "        parameter is set to true, the script will set up the EveryTime ";
  1242.     println "        Macro to create a log, execute the commands you put here, close ";
  1243.     println "        the log and restart. If you want to define the macro in the ";
  1244.     println "        Debugger Prefs file, put a false value in Use_MacsBug_Log_Macro.";
  1245.     println "        To ensure the EveryTime macro is cleared under all circumstances,";
  1246.     println "        put true into Use_MacsBug_Log_Macro and put 'clear' in this";
  1247.     println "        parameter. Then crashed targets will sit right where ";
  1248.     println "        they crashed. This is good for manual debugging. Possible values";
  1249.     println "        for this parameter are:";
  1250.     println "            theMacro:    A string of valid MacsBug commands, each followed ";
  1251.     println "                        by a semi-colon. For example, the string ";
  1252.     println "                        'ap;how;wh;ip;td;' will put the application name,";
  1253.     println "                        how it crashed, where it crashed, some disassembly";
  1254.     println "                        around the crash point, and the registers, into the";
  1255.     println "                        log. The commands you specify here are wrapped in ";
  1256.     println "                        commands to open a log, close it and restart, so ";
  1257.     println "                        you do not have worry about that  if you use this ";
  1258.     println "                        mechanism to make the macro. ";
  1259.     println "                        ";
  1260.     println "                        If you put an empty string here, the engine will ";
  1261.     println "                        still create a log and restart, but it will be an";
  1262.     println "                        empty file.";
  1263.     println "                        ";
  1264.     println "                        CAUTION: Keep it short, MacsBug is unforgiving ";
  1265.     println "                        for long macros. Also, beware of commands that";
  1266.     println "                        produce so many output lines that MacsBug asks for";
  1267.     println "                        a key press to continue auto-scrolling. Stack";
  1268.     println "                        crawls based on A7 tend to produce too much.";
  1269.     println "            'clear':     This is a special value to clear the EveryTime ";
  1270.     println "                        macro. Even if the macro is defined in the Debugger";
  1271.     println "                        Prefs file, it will be cleared.";
  1272.     println "";
  1273.     println "    Quit_All_First";
  1274.     println "        You may want to run the LaunchQuit engine with an application ";
  1275.     println "        running in the background, or perhaps several. Normally, the";
  1276.     println "        script tries to quit all applications except Finder before ";
  1277.     println "        calling the engine. This Boolean parameter allows you to skip";
  1278.     println "        that process. Possible values are:";
  1279.     println "            true:     The script will try to quit all applications before ";
  1280.     println "                    starting the engine. This is slower but ensures there ";
  1281.     println "                    are no leftover applications taking up space. ";
  1282.     println "            false:    The script will ignore whatever applications were ";
  1283.     println "                    running at the time it started. ";
  1284.     println "                    ";
  1285.     println "                    CAUTION: These applications will stay in the background ";
  1286.     println "                    for the whole run, but in the current implementation ";
  1287.     println "                    they are not re-launched after a crash.";
  1288.     println "";
  1289.     println "    Make_Aliases";
  1290.     println "        When the script configures the target with several Control Panels, ";
  1291.     println "        you can speed up the process by allowing it to create aliases ";
  1292.     println "        and move them to the Apple Menu Items folder. When the script";
  1293.     println "        tries to open a Control Panel it looks first for the alias.";
  1294.     println "        Possible values are:";
  1295.     println "            true:     The script will create an alias for all Control Panels ";
  1296.     println "                    used during the run, and put the alias in the Apple ";
  1297.     println "                    Menu Items folder.";
  1298.     println "                    ";
  1299.     println "                    CAUTION: In the current implementation the aliases";
  1300.     println "                    are not removed after the run is complete.";
  1301.     println "            false:    The script will not create an alias for Control Panels. ";
  1302.     println "";
  1303.     println "    Custom_Testing";
  1304.     println "        (Not implemeted well enough for production use).";
  1305.     println "        This Boolean value specifies if you want to execute the custom";
  1306.     println "        task defined in the LQCustom.lib. You can define this task";
  1307.     println "        any way you want. When the launch sequence is complete for ";
  1308.     println "        each application, the engine executes the custom task. ";
  1309.     println "        After the custom task returns successfully, the engine attempts ";
  1310.     println "        to quit the application normally. Possible values are:";
  1311.     println "            true:     The engine will execute the custom task.";
  1312.     println "            false:    The engine will not execute the custom task. ";
  1313.     println "";
  1314. #        println "    Use_Arbitrator_If_Available";
  1315. #        println "        If the Arbitrator script is running, connect to it and";
  1316. #        println "        use it to keep track of which test def is currently ";
  1317. #        println "        executing, and also to prevent multiple launching of";
  1318. #        println "        applications that check for serial number conflicts";
  1319. #        println "        over the network. Possible values are:";
  1320. #        println "            true:     Connect to the Arbitrator if it is running.";
  1321. #        println "            false:    Do not connect to the Arbitrator. ";
  1322. end;
  1323.  
  1324. ################################################################################
  1325. ####################            End of Calls                ####################
  1326. ################################################################################